home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 44 / Amiga Format CD44 (1999-08-26)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-10].iso / -serious- / wb / merlin / docs / merlin.doc < prev    next >
Text File  |  1999-07-12  |  37KB  |  1,137 lines
  1.  
  2.  
  3.  
  4.  
  5.                Copyright (C) 1998-1999  by Arend-Paul Spijkermann
  6.             Software and documentation written by A.Paul Spijkerman
  7.  
  8.                             All Rights Reserved
  9.  
  10.  
  11.  
  12.                     All information in this documentation
  13.                   is subject to change without prior notice
  14.  
  15.  
  16.  
  17.  
  18.                                Project Merlin
  19.                                ==============
  20.  
  21.          The Merlin project is a number of programs i have written
  22.              to configure my system as I would like it to be.
  23.               An easy way to generate a GUI for your system.
  24.  
  25.          It consists of the Master Control Program and its server,
  26.          the scheduler, the soundhandler, a number of programs
  27.          to generate GUI's for directorys and drives and
  28.          programs to start it.
  29.          There are more elements, but they are not included yet.
  30.  
  31.  
  32.            You can make a Popup MenuButton window with it.
  33.               Make a Browser type of workbench with it and
  34.                  Emulate workbench or windows with it.
  35.            Use your creativity and make your Amiga into YOUR Amiga.
  36.               (These are not hacks, it is a layer upon the OS)
  37.             The system works on any Amiga witk OS 2.0 or better.
  38.             It needs no external products, it only uses a couple
  39.               of the most basic libraries and is very portable.
  40.  
  41.  
  42.  
  43.         Ever downloaded a "menu button" popup tool and was
  44.         disapointed about the lack of options.
  45.         Because you couldn't do simple things like group buttons
  46.         by coloring them or draw a border around them.
  47.  
  48.         Have you ever wondered why you can't control your system
  49.         with a nice GUI like your favourite aplications ?
  50.  
  51.         Ever wanted to add a "Start" button to your system ?
  52.  
  53.         Ever wanted to setup an easy GUI for someone who
  54.         doesn't know much about computers with only the
  55.         applications the need. And a password secured icon
  56.         for the system operator to start an editor or something.
  57.  
  58.         Ever wanted to make a multi-user workbench ?
  59.         With or without password control ?
  60.  
  61.         Ever wanted to make a special "brag" workbench, or a
  62.         workbench with your favourite pictures.
  63.         Which you can take with you on disk ?
  64.  
  65.         This is not a Workbench replacement but a system to make
  66.         a GUI to your system as YOU see it, a sort of BrowserBench.
  67.         You can group buttons without having to move programs to
  68.         other harddisks or CDroms.
  69.  
  70.  
  71.         Configuration is easy. You don't have to give the position
  72.         of all elements. Just how they are orientated to the other
  73.         elements. This is done by placing them in horizontal or
  74.         vertical groups.
  75.         When you want to make 3 columns with 3 buttons you first have
  76.         to make a horizontal group for the rows of columns. And inside
  77.         that you have 3 vertical groups for the buttons.
  78.         It would look like something like this:
  79.         (Note that the indentations are only there to show the structure)
  80.  
  81.  
  82. HGROUP
  83.  VGROUP
  84.   TEXT    "Games"
  85.   BUTTON  "Game1"      RUN "dh1:games/game1"
  86.   BUTTON  "Game2"      RUN "dh1:games/game1"
  87.   BUTTON  "Game3"      RUN "dh1:games/game1"
  88.  ENDGROUP
  89.  VGROUP
  90.   TEXT    "Utils"
  91.   BUTTON  "Dirwork"    RUN "dh1:utils/DirWork"
  92.   BUTTON  "Edit"       RUN "dh1:utils/Editor"
  93.   BUTTON  "ARTM"       RUN "dh1:utils/ARTM"
  94.  ENDGROUP
  95.  VGROUP
  96.   TEXT    "Internet"
  97.   BUTTON  "Browser"    RUN "dh1:Inet/Browser"
  98.   BUTTON  "Mail"       RUN "dh1:Inet/Mail"
  99.   BUTTON  "Irc"        RUN "dh1:Inet/Irc"
  100.  ENDGROUP
  101. ENDGROUP
  102.  
  103.  
  104.  
  105.         Because no position is fixed things like resizing a window
  106.         is easy to implement. When you resize a window the engine
  107.         recalculates all positions. Also lists will show more
  108.         lines if there is more room after a resize.
  109.         Even better you can specify things like line thickness and the
  110.         distances between objects and groups. So you can change the
  111.         looks to your licking.
  112.         Every object can have its own font and colors.
  113.  
  114.         It is Based on ASCII type readable and editable description
  115.         files for GUI's .. GUI files can be generated by
  116.         some of the suplied programs.
  117.  
  118.         You are not limited to just buttons or text objects, there
  119.         are Clickable pictures with dithering, animations,
  120.         clocks, lists with scrollers, lines etc.
  121.  
  122.         There are programs suplied to make windows with Icons
  123.         for drives, and windows with icons for programs.
  124.         This is all done real time with scripts.
  125.         Also these programs can recognize the types of files,
  126.         so you can even display pictures by clicking on icons.
  127.         The best thing is you can browse through directories
  128.         where files have no icons.
  129.         If you click on a directory Icon a GUI file for that
  130.         directory is made by a script and the script executes
  131.         a GUI-browser for that GUI-file.
  132.  
  133.         But there are more interesting features.
  134.         Objects of GUI's can be changed by Arexx scripts
  135.         or external programs.
  136.         Or even better you can use the system as a GUI
  137.         for you arexx program.
  138.  
  139.         Say you wanted to add a currency conversion system
  140.         in the corner of your GUI.
  141.         Or you want to convert Degrees Fahrenheit to
  142.         degrees celsius or vice versa on your GUI.
  143.  
  144.         All you need is the folowing pieces of GUI definition
  145.         in your GUI file, and the arexx scripts in the rexx directory.
  146.  
  147.  
  148.   VGROUP
  149.     HGROUP
  150.      TEXT "HFl. "
  151.      STRINGGADGET SIZE 10  ID 11   run "rx mcp:rexx/GuilderToEuro.rexx %n"
  152.     ENDGROUP
  153.     HGROUP
  154.      TEXT "Euros"
  155.      STRINGGADGET SIZE 10  ID 12   run "rx mcp:rexx/EuroToGuilder.rexx %n"
  156.     ENDGROUP
  157.   ENDGROUP
  158.  
  159.  
  160.   VGROUP    border
  161.     HGROUP
  162.      TEXT "F"     SIZE 1
  163.      STRINGGADGET SIZE 6  ID 13   run "rx mcp:rexx/FahrenheitToCelsius.rexx %n"
  164.     ENDGROUP
  165.     HGROUP
  166.      TEXT "C"     SIZE  1
  167.      STRINGGADGET SIZE  6  ID 14   run "rx mcp:rexx/CelsiusToFahrenheit.rexx %n"
  168.     ENDGROUP
  169.   ENDGROUP
  170.  
  171.  
  172.  
  173.  
  174.         And how about a Stop button to shut the system down.
  175.         You probably say a stop button isn't that a silly
  176.         shortcoming of the system ??
  177.  
  178.         But wait, what about the Editors on other windows you forgot
  179.         about when you turn the system off. Or files stored in RAM:
  180.  
  181.         Won't programs needs special adaptation to stop and save
  182.         on demand ?.
  183.  
  184.         Well some do. But we have Arexx, how about an arexx script
  185.         that saves the current text in a Cygnus editor with a
  186.         ".TMP" extension.
  187.         Like a reversed startup-sequence.
  188.  
  189.         Wouldn't a software controlled On/Off button be usefull ?
  190.         You press the Off button, all the programs finish and then
  191.         the power is switched off.
  192.         Say you don't play games, then you have a button on the
  193.         joystick you don't use. What about an option to shut the
  194.         system down when you press it as a sort of Soft Off.
  195.         Just stick it next to the On/Off switch, and press it
  196.         before you switch off.
  197.         Sound silly ? Wait untill it saves your document.
  198.         Or what about a lightning storm, you want to switch
  199.         off the system quick not close all programs by hand.
  200.         Have you ever tried to instruct family how to stop all programs.
  201.  
  202.         Do you have an Uninterruptable PowerSuply that powers your system
  203.         a couple of minutes at power failures ?
  204.         What if you are away when the power fails.
  205.         Just wire the warning signal to the joystick button.
  206.         Are you afraid it might fry your joystick port ?
  207.         Just buy an OptoCoupler for a few dollars and solder it
  208.         between joystick and UIP wires.
  209.         An OptoCoupler is a galvanic separation device, it is basically
  210.         a tiny cube with a LED light and a light sensitive switch, all
  211.         PC Power suplies have them.
  212.         You could mount it in a little box with a OFF push button on it.
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.    Using the system
  221.    ================
  222.  
  223.       First time use:
  224.  
  225.  
  226.       To use the provided demonstration archive, you only
  227.       need to unarchive it to a directory.
  228.       Make an assign MCP: to the directory, like:
  229.  
  230.       Assign MCP: RAM:
  231.  
  232.       And execute the "Start" script by typing "MCP:Start".
  233.       If the script lost its script flag while unarchiving
  234.       you need to add "execute" or give the script the
  235.       script flag with "protect MCP:start +S".
  236.  
  237.       The system can be stopped by clicking the Quit button
  238.       or starting the "Stop" script.
  239.  
  240.  
  241.  
  242.  
  243.    The Merlin Project Server
  244.    =========================
  245.  
  246.       Note that there is a ScreenGrab in the main directory.
  247.  
  248.       To be able to use the MCP programs first you need to
  249.       start the server program "MPS".
  250.       
  251.  
  252.       The program is needed for a number of reasons.
  253.       It manages the Public Screen if it is needed.
  254.       It provides Merlin Project tasks with unique
  255.       identification numbers.
  256.       It handles shared data.
  257.       It stops all programs when the system is quited.
  258.       etc..
  259.  
  260.       This program makes use of the "mcp:cfg/screen.mps"
  261.       file where the definitions are.
  262.       Here you can define if the GUI's use the workbench
  263.       screen or a special Public Screen is opend.
  264.  
  265.       Just start MPS  with "Run MPS".
  266.  
  267.  
  268.  
  269.    The Master Control Program (or MCP).
  270.    ====================================
  271.  
  272.       This program handles the GUI's.
  273.  
  274.       Just run it with the name of the GUI file on the
  275.       commandline but don't add the ".mcp" extension.
  276.  
  277.  
  278.    Master Control Program configuration files
  279.    ------------------------------------------
  280.  
  281.       For every GUI you need a to make a configuration file.
  282.       The contents of these files can be split into two
  283.       kinds of data.
  284.       The first half describes general parameters and defines
  285.       labels and such things.
  286.       The second half describes the objects of the GUI and how
  287.       they are placed in the GUI.
  288.  
  289.       It is best to place the items of the first catagorie in
  290.       the first part (begining) of the configuration file
  291.       because some of the items can only be used after they
  292.       are mentioned. Like the labels.
  293.       Lets call the first part of the configuration file with
  294.       items of the first categorie the "header". And the second
  295.       part the "Gui definition".
  296.  
  297.       Configurations are line based.
  298.       This means that a line can be empty or it contains the
  299.       data of one item or object.
  300.       Data of an object can't be on more then one line.
  301.  
  302.       When spaces need to be used in definitions then place the
  303.       entry between "" characters.
  304.       A good practice would be to place all text which are not
  305.       keywords between "".
  306.  
  307.       Comments can be made every where in the configuration by
  308.       placing a ; after the last relevant data of a line
  309.       and placing the comment after the ; character.
  310.  
  311.  
  312.    The Header part
  313.    --------------
  314.  
  315.       To make the Gui definition more readable you can define labels
  316.       for pens. This means you can use the names of colors instead
  317.       of pen numbers. This is optional.
  318.       In GUI files generated by programs this option is not used.
  319.  
  320.          The template for pen labels is "PEN #nn label"
  321.  
  322.          Examples:
  323.  
  324.          PEN  #0  Grey
  325.          PEN  #1  Black
  326.          PEN  #2  White
  327.          PEN  #3  Blue
  328.  
  329.  
  330.       Also there are labels for fonts, this means you can make
  331.       a label for each type of object.
  332.       If you want to change the font used by buttons you only need
  333.       to change the definition of the label instead of changing
  334.       the font in each button definition.
  335.  
  336.          The template is  "FONT   "Fontname.font"  FontSize  Label"
  337.  
  338.          Examples:
  339.  
  340.          FONT  "Topaz.font"       8    ButtonFont
  341.          FONT  "Topaz.font"       8    TextFont
  342.  
  343.  
  344.       Also there labels for the definition of pictures.
  345.       This is usefull if a picture is used many times like
  346.       by the mdir program that turns the contents of a directory
  347.       in a GUI with icons.
  348.       Note that only the IFF type of pictures are recognized.
  349.       Note that 24bit type of IFF's can be used.
  350.  
  351.          The template is  "IFF    "path/picture.iff"   Label"
  352.  
  353.          Examples:
  354.  
  355.          IFF "mcp:iff/dir.iff"  dirPic
  356.          IFF "mcp:iff/doc.iff"  docPic
  357.          IFF "mcp:iff/exe.iff"  exePic
  358.          IFF "mcp:iff/arc.iff"  arcPic
  359.          IFF "mcp:iff/pic.iff"  picPic
  360.          IFF "mcp:iff/dat.iff"  datPic
  361.          IFF "mcp:iff/snd.iff"  sndPic
  362.  
  363.  
  364.       Line thickness of objects and the number of pixels between
  365.       certain types of objects can be controlled.
  366.       For this there are 4 item types which can each be
  367.       defined once in a configuration file.
  368.  
  369.       These keywords are follow by two parameters who correspond
  370.       with number of pixels in the X and the Y direction.
  371.  
  372.       Available items are:
  373.  
  374.       SAW X Y
  375.       SAG X Y
  376.       SAO X Y
  377.       LTX X Y
  378.  
  379.       SAW means Space Around Window
  380.       SAG means Space Around Group
  381.       SAO means Space Around Object
  382.       LTX means Line thickness
  383.  
  384.       The "Space Around Window" is the numbers of pixels on the
  385.       inside edge of a window that is left empty.
  386.  
  387.       The "Space Around Group" is the space in numbers of pixels that is
  388.       created at the inside AND the outside of the border of a group
  389.       of objects.
  390.  
  391.       The "Space Around Object" is the space in numbers of pixels that is
  392.       left empty around an object.
  393.  
  394.       The "Line Thickness" is the thickness of lines in pixels that
  395.       is used for all borders and line objects.
  396.  
  397.          Examples:
  398.  
  399.          SAW  2  1       ; SpaceAroundWindow X Y
  400.          SAG  3  2       ; SpaceAroundGroup  X Y 
  401.          SAO  2  1       ; SpaceAroundObject X Y
  402.          LTX  2  1       ; LineThickness     X Y
  403.  
  404.  
  405.       The default size of buttons and strings can be defined with
  406.       one line.
  407.       This is usefull if a GUI contains a lot of buttons of the
  408.       same size. You don't need to specify the size for each object.
  409.  
  410.          Template:   "DEFAULTSIZE nnn"
  411.  
  412.          Example:
  413.  
  414.          DEFAULTSIZE 10
  415.  
  416.  
  417.       The background color of a window can be defined.
  418.       Note that the background is only colored if the pen
  419.       definition is different as the default color of the
  420.       window. This can be the case if a color is translated
  421.       to a pen with the same color as the window, if the
  422.       number of pens is smaller as the number or pens used in
  423.       the configuration.
  424.       Note that this is best used AFTER the pen labels.
  425.  
  426.          Template:   "WINDOWCOLOR nnn/label"
  427.  
  428.          Examples:
  429.  
  430.          WINDOWCOLOR   grey
  431.          WINDOWCOLOR   3
  432.  
  433.  
  434.       The title of a window can be changed.
  435.       Note that if you use spaces you need to use "".
  436.  
  437.          Template:   "WINDOWTITLE "string of text""
  438.  
  439.          Example:
  440.  
  441.          WINDOWTITLE   "Main"
  442.  
  443.  
  444.       The MCP system optionally stores the last position and size
  445.       of GUI windows. If you want to use this you need to put
  446.       the SAVEWINDOWPOS in the header.
  447.       The data is saved for each GUI in the mcp:temp/ directory.
  448.  
  449.          Template:   "SAVEWINDOWPOS"
  450.  
  451.  
  452.       You can define the position of where the window is opened on
  453.       the screen.
  454.       Note that this can be overruled if there is saved window
  455.       size and position available.
  456.  
  457.          Template:   "WINDOWPOS X Y"
  458.  
  459.          Example:
  460.  
  461.          WINDOWPOS  20  20
  462.  
  463.  
  464.       After the GUI is completely drawn a program can be
  465.       optionally started.
  466.       This can for example be a program that changes some
  467.       of the GUI objects or fills the lists.
  468.  
  469.          Template:   "DEFAULTPROG "Path/program %x""
  470.  
  471.          Example:
  472.  
  473.          DEFAULTPROG   "mcp:rexx/main.rexx %n"    ;%n=port number, %s=prog name
  474.  
  475.          Note that there are some variables that can be used that are
  476.          filled in by the system at the moment of use.
  477.          These variables work exactly like in those in programs written
  478.          in the C language.
  479.  
  480.          %n is an integer which is the "number" of this program
  481.             This number is needed when the program want to
  482.             interface with
  483.  
  484.          %s is a string with the name of the GUI (the config name with
  485.             the path and .mcp part)
  486.  
  487.          %i is the ID number of the object, in case of the Defaultprog
  488.             it is 1, because objects with the ID number not defined
  489.             give the value 0 as result.
  490.             This is usefull in case you make one script for all the
  491.             RUN calls of a GUI, so you only have to mention an ID once
  492.             so you can't have a wrong ID on a command line.
  493.  
  494.  
  495.  
  496.  
  497.    The Gui definition part
  498.    -----------------------
  499.  
  500.       Note that if you want to change or read a GUI object
  501.       with an external program you will need to give the
  502.       object an ID number. This is a 32 bit unsigned number.
  503.       This number needs to be unique in a GUI configuration file.
  504.       (Unless you want to use duplicate objects)
  505.       If you want to use the same Arexx scripts in different
  506.       GUI's you need to keep the ID's unique through the system.
  507.       This means if you use ID 12 for a stringgadget where you
  508.       can enter the temperature in degrees celsius you can beter
  509.       not use ID 12 in other configs for other types of objects.
  510.  
  511.  
  512.       Configuration is easy. You don't have to give the position
  513.       of all elements. Just how they are orientated to the other
  514.       elements. This is done by placing them in horizontal or
  515.       vertical groups.
  516.       This part of the configuration basically consists of
  517.       nested groups with GUI objects in them.
  518.  
  519.       When you want to make 3 columns with 3 buttons you first have
  520.       to make a horizontal group for the rows of columns. And inside
  521.       that you have 3 vertical groups for the buttons.
  522.       It would look like something like this:
  523.       (Note that the indentations are only there to show the structure,
  524.        config files are better readable if you enter them this way)
  525.  
  526.  
  527. HGROUP
  528.  VGROUP
  529.   TEXT    "Games"
  530.   BUTTON  "Game1"      RUN "dh1:games/game1"
  531.   BUTTON  "Game2"      RUN "dh1:games/game1"
  532.   BUTTON  "Game3"      RUN "dh1:games/game1"
  533.  ENDGROUP
  534.  VGROUP
  535.   TEXT    "Utils"
  536.   BUTTON  "Dirwork"    RUN "dh1:utils/DirWork"
  537.   BUTTON  "Edit"       RUN "dh1:utils/Editor"
  538.   BUTTON  "ARTM"       RUN "dh1:utils/ARTM"
  539.  ENDGROUP
  540.  VGROUP
  541.   TEXT    "Internet"
  542.   BUTTON  "Browser"    RUN "dh1:Inet/Browser"
  543.   BUTTON  "Mail"       RUN "dh1:Inet/Mail"
  544.   BUTTON  "Irc"        RUN "dh1:Inet/Irc"
  545.  ENDGROUP
  546. ENDGROUP
  547.  
  548.  
  549.  
  550.       This might look complicated, but if you know how your
  551.       GUI is gonna look like it is very simple.
  552.       You need to remember that all objects need to be
  553.       arranged in horizontal and vertical groups.
  554.  
  555.       Just draw your GUI on a piece of paper and draw boxes
  556.       around horizontal and vertical groups of objects.
  557.       Then draw boxes on the horizontal and vertically arranged 
  558.       groups until the biggest box is the window itself.
  559.       
  560.       Then start to write down the information of the biggest
  561.       box and then write down the information of the objects
  562.       inside the box.
  563.  
  564.       You always need to start the gui configuration with
  565.       a HGROUP or VGROUP object.
  566.  
  567.  
  568.  
  569.    Useable Objects
  570.    ---------------
  571.  
  572.       Horizontal and vertical groups.
  573.       Groups can have optional borders.
  574.       These are just the HGROUP and VGROUP keyword followed by
  575.       options:
  576.       note:  Groups MUST be terminated with ENDGROUP
  577.  
  578.       HGROUP, VGROUP
  579.  
  580.          Example:
  581.  
  582.          HGROUP  BORDERUP  BCOLOR lgrey
  583.  
  584.          options:
  585.  
  586.          BORDER,     GROOVE        <- Draws a 2D groove around a group
  587.          RIDGE                     <- Draws a 2D ridge around a group
  588.          BORDERUP,   UP            <- Gives the group a 3D "UP" look
  589.          BORDERDOWN, DOWN          <- Gives the group a 3D "Down" look
  590.          BCOLOR <label>/<color>    <- Changes the background color of the group
  591.  
  592.  
  593.  
  594.  
  595.       Text objects.
  596.       These are a line of text, with an optional border.
  597.       Note that the text must come after the TEXT keyword.
  598.  
  599.       TEXT "text"
  600.  
  601.          Example:
  602.  
  603.          Text "test"  BCOLOR blue  BOLD
  604.  
  605.          options:
  606.  
  607.          BORDER,     GROOVE        <- Draws a 2D groove around a group
  608.          RIDGE                     <- Draws a 2D ridge around a group
  609.          BORDERUP,   UP            <- Gives the text a 3D "UP" look
  610.          BORDERDOWN, DOWN          <- Gives the text a 3D "Down" look
  611.          BORDERINV,  INV           <- Invisible border, makes object bigger
  612.          <FontLabel>               <- Defines the font to be used
  613.          BCOLOR label/nr           <- Defines the background color
  614.          FCOLOR label/nr           <- Defines the character color
  615.          CLOCK                     <- turns this object in a clock
  616.          ITALIC, BOLD, UNDER       <- changes font style
  617.          SHADOW                    <- draws a black shadow under characters
  618.          SHADOW2                   <- draws a further shadow (can be combined with SHADOW)
  619.          SIZE nnn                  <- Length of the object in characters
  620.          ID nn                     <- Identification number
  621.  
  622.  
  623.  
  624.       Button objects.
  625.       These are button gadgets that start programs when clicked on.
  626.       Note that the text must come after the BUTTON keyword.
  627.  
  628.       BUTTON  "text"
  629.  
  630.          Example:
  631.  
  632.          BUTTON "Test"  ID 123  BCOLOR blue  FCOLOR black  RUN "Test"
  633.  
  634.          options:
  635.  
  636.          <Font>                    <- label of the font to be used (optional)
  637.          ID  nnn                   <- identification number
  638.          BCOLOR label/nr           <- Defines the background color
  639.          FCOLOR label/nr           <- Defines the character color
  640.          RUN    "path/program %n"  <- program to run (%n = node number, %i = ID)
  641.          STACK  nnn                <- If you need more stack then 4096 bytes
  642.          SIZE   nnn                <- Length of the object in characters
  643.          QUIT                      <- Quits program if clicked
  644.  
  645.  
  646.  
  647.       QuitButton object.
  648.       These are button gadgets that quit the program when clicked on.
  649.  
  650.       QUITBUTTON
  651.  
  652.          options:
  653.  
  654.          <font>                    <- label of the font to be used (optional)
  655.          SIZE nn                   <- Length of the object in characters
  656.  
  657.  
  658.  
  659.       CheckMark object.
  660.       These are button gadgets that can be toggled and read by
  661.       external programs.
  662.  
  663.       CHECKMARK
  664.  
  665.          options:
  666.  
  667.          <font>                    <- label of the font to be used (optional)
  668.          BCOLOR label/nr           <- Defines the background color
  669.          FCOLOR label/nr           <- Defines the character color
  670.          STATE    0/1              <- Default state of the CheckMark object
  671.          ID nnn                    <- Identification number
  672.  
  673.  
  674.  
  675.       Picture object.
  676.       These are pictures loaded from IFF files and converted to
  677.       the screen depending on the pens available.
  678.       Note that a program can be started when a picture is clicked on.
  679.       Note that there a couple of dither modes.
  680.       Dither mode 1 is for pictures with no color change from pixel to pixel
  681.       Dither mode 2 is for pictures of persons with color change.
  682.       Note that in HAM or GREY modes only always mode 2 is used.
  683.  
  684.  
  685.       PICTURE
  686.  
  687.          Example:
  688.  
  689.          PICTURE boing  BORDERUP
  690.  
  691.          Options:
  692.  
  693.          <label>                   <- label of the picture to be used
  694.          BORDER,     GROOVE        <- Draws a 2D groove around a picture
  695.          RIDGE                     <- Draws a 2D ridge around a picture
  696.          BORDERUP,   UP            <- Draws a 3D "up" border around a picture
  697.          BORDERDOWN, DOWN          <- Draws a 3D "up" border around a picture
  698.          RUN    "path/program %n"  <- program to run (%n = node number, %i = ID)
  699.          STACK  nnn                <- If you need more stack then 4096 bytes
  700.          DITHER  nn                <- Optional dither modes
  701.  
  702.  
  703.       StringGadget object.
  704.       These are text gadgets that can be filled with text that can
  705.       be read by external programs.
  706.       The program is started when return is pressed in the gadget.
  707.  
  708.  
  709.       STRINGGADGET
  710.  
  711.          Options:
  712.  
  713.          <Font>                    <- label of the font to be used (optional)
  714.          SIZE nnn                  <- Length of the object in characters
  715.          ID   nnn                  <- Identification number
  716.          RUN  "Path/file %n"       <- program to run (%n = node number, %i = ID)
  717.          STACK nnn                 <- If you need more stack then 4096 bytes
  718.          BCOLOR label/nr           <- Defines the background color
  719.          FCOLOR label/nr           <- Defines the hand color
  720.  
  721.  
  722.       Doscommand object.
  723.       This is a string gadget that will try to execute the
  724.       string of text that is in it when return is pressed.
  725.  
  726.  
  727.       DOSCOMMAND
  728.  
  729.          Options:
  730.  
  731.          <Font>                    <- label of the font to be used (optional)
  732.          SIZE nnn                  <- Length of the object in characters
  733.          BCOLOR label/nr           <- Defines the background color
  734.          FCOLOR label/nr           <- Defines the hand color
  735.  
  736.  
  737.       Animation Object.
  738.       This is a little box with a moving "hand" to show the computer
  739.       still works. Might be nice if your a programmer.
  740.  
  741.       ANIM
  742.  
  743.          Options:
  744.  
  745.          BCOLOR label/nr           <- Defines the background color
  746.          FCOLOR label/nr           <- Defines the hand color
  747.  
  748.  
  749.       Line Object.
  750.       This is supposed to be a separation line between objects
  751.       or groups of objects. Works best if a horizontal line is
  752.       used in a vertical group and vice versa.
  753.       The line will be almost as wide as the group it will draw in.
  754.  
  755.  
  756.       LINE
  757.  
  758.          Options:
  759.  
  760.          HORIZONTAL                <- Switch to draw a horizontal line
  761.          VERTIKAL                  <- Switch to draw a vertical line
  762.  
  763.  
  764.       Void object.
  765.       Defines a piece of space.
  766.       Usefull if you want a gap between objects.
  767.       You make make colored boxes with it if it is the only
  768.       object in a colored group. (see the colortest.mcp)
  769.  
  770.       VOID
  771.  
  772.          Options:
  773.  
  774.          HORIZONTAL                <- Only gives the object width
  775.          VERTIKAL                  <- Only gives the object height
  776.          SOLID                     <- Gives both width and Height
  777.          WIDTH  nnn                <- define width in pixels
  778.          HEIGHT nnn                <- define height in pixels
  779.  
  780.  
  781.       List object.
  782.       Defines a list with a scroller.
  783.       Objects that are clicked on are executed.
  784.  
  785.       Note that lists can be "loaded" in different ways.
  786.       Methode one is giving it the name of a file with the list in it.
  787.       The file would have the following format:    TEXT ".."  RUN "path/prog"
  788.       Where TEXT is the text visible text, and RUN the program executed.
  789.       The other methode to load a list is by an external program or script
  790.       That is executed by a button or the DefaultProg option.
  791.  
  792.       Note that SMODE is the way a list behaves optionally when it is clicked.
  793.       0 = nothing
  794.       1 = selected entry flashes
  795.       2 = single selected items are shown hilighted        (default)
  796.       3 = multi selected items are shown hiligthed
  797.  
  798.       Note that AMODE is the action a list performes when it is clicked.
  799.       0 = no action (For instance when the selected items are read by arexx)
  800.       1 = execute the RUN string of the selected item (default)
  801.  
  802.       LIST
  803.  
  804.          Options:
  805.  
  806.          BORDER,     GROOVE        <- Draws a 2D groove around a group
  807.          RIDGE                     <- Draws a 2D ridge around a group
  808.          BORDERUP,   UP            <- Gives the text a 3D "UP" look
  809.          BORDERDOWN, DOWN          <- Gives the text a 3D "Down" look
  810.          BCOLOR label/nr           <- Defines the background color
  811.          FCOLOR label/nr           <- Defines the character color
  812.          SCOLOR label/nr           <- Defines the background color of selected items
  813.          <Font>                    <- label of the font to be used (optional)
  814.          ID nnn                    <- Identification number
  815.          SIZE  nnn                 <- width of the list in characters
  816.          LINES nnn                 <- heigth of the list in lines
  817.          SMODE nnn                 <- selection mode
  818.          AMODE nnn                 <- action mode
  819.          LISTFILE  "path/file"     <- file to load entries from
  820.  
  821.  
  822.       Clock object.
  823.       Shows the time in 24 hour format.
  824.  
  825.  
  826.       CLOCK
  827.  
  828.          Options:
  829.  
  830.          BCOLOR label/nr           <- Defines the background color
  831.          FCOLOR label/nr           <- Defines the character color
  832.          ITALIC, UNDER, BOLD       <- Defines font styles
  833.          BORDER,     GROOVE        <- Draws a groove around a group
  834.          BORDERUP,   UP            <- Gives the text a 3D "UP" look
  835.          BORDERDOWN, DOWN          <- Gives the text a 3D "Down" look
  836.          BORDERINV,  INV           <- Invisible border, makes object bigger
  837.          <FontLabel>               <- Defines the font to be used
  838.  
  839.  
  840.  
  841.  
  842.  
  843.    Interaction of MCP with other programs
  844.    --------------------------------------
  845.  
  846.  
  847.       When MCP is started or on object is accessed a program
  848.       can be executed.
  849.       These programs can interact with MCP to read data from
  850.       certain objects or to change certain objects.
  851.  
  852.       This can be done through the Arexx port or the program message port.
  853.  
  854.       The Arexx port makes it possible to use extra commands in
  855.       arexx scripts.
  856.       The program message port allows programs in a higher language to
  857.       interact with MCP.
  858.       An example of such a program is the McpMsg program, which can
  859.       do about all the things the arexx commands can do.
  860.  
  861.       The McpMsg program can be used in DOS scripts to change the
  862.       GUI .. or be started from programs with an option to
  863.       execute programs.
  864.  
  865.       I have looked if there are options to do this from REBOL
  866.       but have found none so far....
  867.  
  868.  
  869.       If you start an arexx script you need to use %n at the
  870.       end of the command line so the script knows which
  871.       arexx port to access.
  872.       You need to add something like the folowing to your
  873.       scripts so it uses the correct arexx port:
  874.  
  875.  
  876.          Arg node_number                /* node we were run from */
  877.          Host = 'MCPREXX.'node_number   /* the Trion MCP Arexx port */
  878.          Options results
  879.          Address value host
  880.          options failat 15
  881.  
  882.  
  883.          /* say "node: "node_number */
  884.          if node_number = "" then do
  885.             say "error .. rexx script not started with %n on command line"
  886.             exit 1
  887.          end
  888.  
  889.  
  890.       When you start a DOS script you also need to add the %n at
  891.       the end of the command line.
  892.       The script needs a couple of lines to read the number.
  893.       A script to change a text can look something like this:
  894.  
  895.  
  896.          .key number
  897.          .def number="1"
  898.  
  899.           mcp:bin/McpMsg  NODE <number>  WRITESTRING  ID 1  STRING "Text"
  900.  
  901.  
  902.  
  903.       Arexx script can not only be used to change some objects on
  904.       in the GUI, you can use MCP as a GUI to your Arexx scripts..
  905.  
  906.       Especially for this each copy of the MCP program has
  907.       registers that are kept in memory even if there is no
  908.       script running at the time.
  909.       Each program has 40 registers that are 32 bit deep unsigned.
  910.  
  911.  
  912.       In a normal program you would "Wait()" until there is
  913.       input for your program. And while you wait all the
  914.       variable hold the state of your program.
  915.       With MCP the register hold the state of your program.
  916.       Your program can consist of a number of arexx scripts,
  917.       a script for each object accessed.
  918.       Or you could make a big program and start the program for
  919.       each object with the ID number of the object on the command
  920.       line. Then the program needs to figure out what to do
  921.       for each object. You might want to use the %i code on the
  922.       end of the command line for the ID number, so you can't
  923.       have a wrong ID when you changed the ID field.
  924.       Look at the rexx/list.rexx script for an example of this.
  925.  
  926.       Earlier in the document there is a description of how to
  927.       make a system that converts currency's or Degrees fahrenheit
  928.       to celsius and reverse. The scripts for this can be
  929.       found in directory "mcp:rexx/".
  930.       Other possibilities could be to count the number of clicks of
  931.       a button in a register.
  932.       You could make a Volume control with 2 buttons, and 2 scripts
  933.       that use a register and execute the SndEvent program.
  934.  
  935.  
  936.  
  937.    Available commands
  938.    ------------------
  939.  
  940.    GET and SET register commands
  941.  
  942.       With these commands the registers can be changed and read.
  943.       There are 40 registers, each 32 bits wide and unsigned.
  944.  
  945.          Arexx template:      SetReg  "REG/N/A,VALUE/N"
  946.          Arexx template:      GetReg  "REG/N/A"
  947.  
  948.          Examples:
  949.  
  950.          write value 123 to register 6
  951.  
  952.          SetReg "Reg 6 Value 123"
  953.          SetReg "6 123"
  954.  
  955.          print the contents of register 6 and 7
  956.  
  957.          GetReg "6"
  958.          reg6 = result
  959.          Say "Register6="reg6
  960.  
  961.          GetReg "Reg=7"
  962.          reg7 = result
  963.          Say "Register7="reg7
  964.  
  965.  
  966.          These two also seem to be present:
  967.  
  968.          Arexx template:      Get  "REG=REGISTER/K/N/A"
  969.          Arexx template:      Set  "REG=REGISTER/K/N/A,VALUE/N/A"
  970.  
  971.  
  972.          Set    "Reg 7 Value" 56
  973.          Set    "Reg 7" 56
  974.  
  975.          GetReg "Reg=7"
  976.          reg7 = result
  977.          Say "Register7="reg7
  978.  
  979.  
  980.          McpMsg GET  NODE 1 ID 1
  981.          McpMsg SET  NODE 1 ID 1 VAR 1
  982.  
  983.  
  984.  
  985.    WriteString
  986.  
  987.       This command can be used to change Text, Stringgadget and Button
  988.       Objects however, Button objects need a little work.
  989.  
  990.          Arexx template:      WriteString  "ID/N/A,STRING/F"
  991.  
  992.          WriteString "ID 12 STRING text"
  993.          WriteString "12 text"
  994.  
  995.          McpMsg WRITESTRING NODE 1 ID 1 STRING "string"
  996.  
  997.  
  998.  
  999.    ReadString
  1000.  
  1001.       This command can be used to read a string from StringGadgets
  1002.  
  1003.          Arexx template:      ReadString  "ID/N/A"
  1004.  
  1005.          ReadString "ID 12"
  1006.          ReadString "12"
  1007.  
  1008.          McpMsg READSTRING  NODE 1 ID 1
  1009.  
  1010.  
  1011.    ReadState
  1012.  
  1013.       This command can be used to read the state of a CheckMark object
  1014.  
  1015.          Arexx template:      ReadState  "ID/N/A"
  1016.  
  1017.          ReadState "ID 3"
  1018.          ReadState "3"
  1019.  
  1020.          McpMsg READSTATE   NODE 1 ID 1
  1021.  
  1022.  
  1023.    ChangeState   CheckMark
  1024.  
  1025.       This command can be used to change the state of a CheckMark object
  1026.  
  1027.          Arexx template:      ChangeState  "ID/N/A,STATE/N"
  1028.  
  1029.          ChangeState "ID 4 STRING" State
  1030.          ChangeState "4" State
  1031.  
  1032.          McpMsg CHANGESTATE NODE 1 ID 1 VAR 0/1
  1033.  
  1034.  
  1035.  
  1036.    EmptyList
  1037.  
  1038.       This command can be used to empty a list object.
  1039.  
  1040.          Arexx template:      EmptyList  "ID/N/A"
  1041.  
  1042.          EmptyList "ID 6"
  1043.          EmptyList "6"
  1044.  
  1045.          McpMsg EMPTYLIST   NODE 1 ID 1
  1046.  
  1047.  
  1048.    AddToList
  1049.  
  1050.       This command can be used to add lines to list objects.
  1051.  
  1052.       This command will install two strings for each object
  1053.       in a list. The first one is the text that is displayed.
  1054.       The second one is the program executed when you click on
  1055.       the item in the list.
  1056.  
  1057.       Note that in the Arexx example underscores are used.
  1058.       I couldn't find a way to get two strimgs with spaces in
  1059.       them to the program. So you need to replace spaces with
  1060.       underscores. The program will remove the underscores.
  1061.       Note that this is not a problem with the McpMsg program,
  1062.       however if a string contains spaces you need to place
  1063.       it between "" on the command line.
  1064.  
  1065.  
  1066.          Arexx template:      AddToList  "ID/N/A,STRING/A,RUN/A"
  1067.  
  1068.          AddToList "ID 6 STRING list_tst RUN test_tst"
  1069.          AddToList "6 list_tst test_tst"
  1070.  
  1071.          McpMsg ADDTOLIST   NODE 1 ID 1 STRING "list tst" RUN "test tst"
  1072.  
  1073.  
  1074.    ClearList
  1075.  
  1076.       This command can be used to unselect all selected items in lists
  1077.  
  1078.          Arexx template:      ClearList  "ID/N/A"
  1079.  
  1080.  
  1081.    GetFirstItem, GetNextItem
  1082.  
  1083.       Read the selected Items of a list
  1084.  
  1085.       Note that the GetItem commands reads the invisible/second string,
  1086.       which normally is the "run" string.
  1087.       This is done so you can add FI a file size to the name in the
  1088.       visible field, but only have the clean name in the invisible field.
  1089.       So you need to fill both fields.
  1090.       Note that rc=0 if there is a string, and rc=1 if there is no
  1091.       string. I tried to make this the line number, and 65535 for no line
  1092.       but the interpreter didn't like it very much.
  1093.  
  1094.  
  1095.          Arexx template:      GetFirstItem  "ID/N/A"
  1096.          Arexx template:      GetNextItem   "ID/N/A"
  1097.  
  1098.          Examples:
  1099.  
  1100.          /* copy selected items to other list */
  1101.  
  1102.          end = 0
  1103.          GetFirstItem 10
  1104.          end = rc
  1105.          str = result
  1106.  
  1107.          do while end = 0
  1108.             AddToList "20" str "test"
  1109.  
  1110.             GetNextItem 10
  1111.             end = rc
  1112.             str = result
  1113.          end 
  1114.  
  1115.  
  1116.    Quit
  1117.  
  1118.       Quit the MCP program
  1119.  
  1120.          Arexx template:      Quit  ""
  1121.  
  1122.          Quit
  1123.  
  1124.  
  1125.    Pause
  1126.  
  1127.       Creates a pause in the Arexx script.
  1128.       Note the time is in 1/50th seconds. So 50 is one second.
  1129.       Use it wisely, because it blocks the program while
  1130.       pausing. You could use it if you want to display text before
  1131.       usind the Quit command.
  1132.  
  1133.          Arexx template:      Pause  "TIME/N/A"
  1134.  
  1135.          Pause 100           /* pause of 2 seconds */
  1136.  
  1137.